KaTeX (2/n): Support horizontal and vertical offsets for spans #1452

rajveermalviya · 2025-04-01T16:40:56Z

Stacked on top of: #1408

Web	Flutter

Related: #46

gnprice · 2025-04-22T23:25:56Z

lib/model/content.dart

+sealed class KatexNode extends ContentNode {
+  const KatexNode({super.debugHtmlNode});
+}
+
+class KatexSpanNode extends KatexNode {


One point that I noticed while developing #1478 (and checking how my draft of that branch interacted with this PR): it'd be good for this commit:
e268041 content: Handle vertical offset spans in KaTeX content

to get split up like so:

First, an NFC prep commit introduces the distinction between KatexNode and KatexSpanNode. At this stage, the latter is the only subclass of the former.

Then another commit makes the substantive changes this commit is about, including introducing the sibling subclasses KatexVlistNode and KatexVlistRowNode.

One reason that'd be useful is that the split between KatexNode and KatexSpanNode is somewhat nontrivial in itself: some of the references to KatexNode continue to say KatexNode, while others switch to saying KatexSpanNode, so the commit is expressing meaningful information by its choices of which references go which way.

This applies the correct font scaling if the KaTeX content is inside a header.

And rename previous type to KatexSpanNode, also while making it a subtype of KatexNode.

Implement handling most common types of `vlist` spans.

Negative margin spans on web render to the offset being applied to the specific span and all the adjacent spans, so mimic the same behaviour here.

gnprice · 2025-04-29T20:26:45Z

It seems like this had slipped through the cracks :-) but it looks ready for review, so I applied the label.

Also rebased now that #1478 is merged, so this now contains only the changes that are specific to this PR.

PIG208

Thanks for the PR! I think the last few commits will need some tests for the more complicated parts. I went over the changes and left some comments, but haven't extensively tested the changes manually yet.

PIG208 · 2025-05-01T21:33:07Z

lib/model/katex.dart

+            _logError('KaTeX: Unsupported CSS property: $property of '
+              'type ${expression.runtimeType}');


One other possibility for this to be logged is when _getEm returns null. I think for debugging purpose, including the value expression might be helpful.

PIG208 · 2025-05-01T21:36:31Z

lib/model/katex.dart

+    if (expression is css_visitor.EmTerm && expression.value is num) {
+      return (expression.value as num).toDouble();
+    }
+    return null;


Let's perhaps have a short dartdoc on what this does and what null means, since the if (…Em != null) continue;'s make this return value quite relevant.

PIG208 · 2025-05-01T21:41:53Z

lib/model/katex.dart

+  final double? heightEm;
+  final double? marginRightEm;
+  final double? topEm;
+  final double? verticalAlignEm;


I think it's a good idea to separate them into groups; to add on this, how about having a short comment before each group explaining how we group them together (like we do with design variables)?

PIG208 · 2025-05-01T21:45:35Z

lib/widgets/content.dart

+    }
+
+    return Container(
+      margin: styles.marginRightEm != null && !styles.marginRightEm!.isNegative


Hmm, !styles.marginRightEm!.isNegative seems a bit contrived. I think isNegative negated is not as clear as >= 0. However, do we need the margin when marginRightEm is 0?

PIG208 · 2025-05-01T21:50:05Z

lib/model/katex.dart

+      styles: inlineStyles != null
+        ? styles.merge(inlineStyles)
+        : styles,


Having tests for this (the case when there are both inline styles and others) might be useful. Not sure how common that is.

PIG208 · 2025-05-01T22:30:18Z

lib/widgets/content.dart

+        child: RichText(text: TextSpan(
+          children: List.unmodifiable(row.nodes.map((e) {
+            return WidgetSpan(
+              alignment: PlaceholderAlignment.baseline,
+              baseline: TextBaseline.alphabetic,
+              child: switch (e) {
+                KatexSpanNode() => _KatexSpan(e),
+                KatexVlistNode() => _KatexVlist(e),
+                KatexNegativeMarginNode() => _KatexNegativeMargin(e),
+              });
+          })))));


looks like this can be replaced with _KatexNodeList(nodes: row.nodes)

PIG208 · 2025-05-01T22:30:41Z

lib/widgets/content.dart

+      child: Text.rich(TextSpan(
+        children: List.unmodifiable(node.nodes.map((e) {
+          return WidgetSpan(
+            alignment: PlaceholderAlignment.baseline,
+            baseline: TextBaseline.alphabetic,
+            child: switch (e) {
+              KatexSpanNode() => _KatexSpan(e),
+              KatexVlistNode() => _KatexVlist(e),
+              KatexNegativeMarginNode() => _KatexNegativeMargin(e),
+            });
+        })))));


_KatexNodeList also seems helpful here.

PIG208 · 2025-05-01T22:34:06Z

lib/widgets/content.dart

+}
+
+class _KatexNegativeMargin extends StatelessWidget {
+  const _KatexNegativeMargin(this.node);


Because the name implies that the margin should be negative, maybe we should also add assertions to ensure that that is true.

PIG208 · 2025-05-01T22:42:29Z

lib/model/katex.dart

  List<KatexNode> _parseChildSpans(dom.Element element) {
-    return List.unmodifiable(element.nodes.map((node) {
-      if (node case dom.Element(localName: 'span')) {
-        return _parseSpan(node);
-      } else {
+    var resultSpans = <KatexNode>[];
+    for (final node in element.nodes.reversed) {
+      if (node is! dom.Element || node.localName != 'span') {
        throw KatexHtmlParseError();
      }
-    }));
+
+      final span = _parseSpan(node);
+      resultSpans.add(span);
+
+      if (span is KatexSpanNode) {
+        final marginRightEm = span.styles.marginRightEm;
+        if (marginRightEm != null && marginRightEm.isNegative) {
+          final previousSpansReversed =
+            resultSpans.reversed.toList(growable: false);
+          resultSpans = [];
+          resultSpans.add(KatexNegativeMarginNode(
+            marginRightEm: marginRightEm,
+            nodes: previousSpansReversed));
+        }
+      }
+    }
+
+    return resultSpans.reversed.toList(growable: false);
  }


Neat solution! A bit tricky to understand. I think we can use QueueList (and with .addFirst) to avoid the hassle of reversing and unreversing the list.

It will be helpful to have tests for this.

PIG208 · 2025-05-01T22:51:55Z

lib/model/katex.dart

+          final pstrutStyles = _parseSpanInlineStyles(pstrutSpan)!;
+          final pstrutHeight = pstrutStyles.heightEm ?? 0;
+
+          // TODO handle negative right-margin inline style on row nodes.


Do we consider this complete after the final commit ("content: Support negative right-margin on KaTeX spans")? I'm not too sure if something else is left to be done here.

This seems to contradict with the earlier assumption that vlist elements contain only the height style.

rajveermalviya mentioned this pull request Apr 1, 2025

Support TeX content in message list #1335

Closed

rajveermalviya force-pushed the pr-tex-content-2 branch from d00e10f to 7ff4f9e Compare April 1, 2025 19:31

gnprice mentioned this pull request Apr 2, 2025

KaTeX (1/n): Initial support for displaying basic KaTeX content #1408

Merged

rajveermalviya force-pushed the pr-tex-content-2 branch from 7ff4f9e to c0dd0a1 Compare April 22, 2025 15:23

gnprice mentioned this pull request Apr 22, 2025

Refactor parts of initial KaTeX handling #1478

Merged

gnprice reviewed Apr 22, 2025

View reviewed changes

rajveermalviya force-pushed the pr-tex-content-2 branch 2 times, most recently from b17033a to 16cb28f Compare April 24, 2025 08:21

rajveermalviya added 6 commits April 29, 2025 13:23

content test [nfc]: Use const for math block tests

7a0c756

content: Support parsing and handling inline styles for KaTeX content

0f5d8f7

content: Scale inline KaTeX content based on the surrounding text

b221285

This applies the correct font scaling if the KaTeX content is inside a header.

content [nfc]: Reintroduce KatexNode as a base sealed class

811f815

And rename previous type to KatexSpanNode, also while making it a subtype of KatexNode.

content: Handle vertical offset spans in KaTeX content

479eced

Implement handling most common types of `vlist` spans.

content: Support negative right-margin on KaTeX spans

376cfe7

Negative margin spans on web render to the offset being applied to the specific span and all the adjacent spans, so mimic the same behaviour here.

gnprice added the maintainer review PR ready for review by Zulip maintainers label Apr 29, 2025

gnprice assigned PIG208 Apr 29, 2025

gnprice force-pushed the pr-tex-content-2 branch from 16cb28f to 376cfe7 Compare April 29, 2025 20:25

PIG208 reviewed May 1, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

KaTeX (2/n): Support horizontal and vertical offsets for spans #1452

KaTeX (2/n): Support horizontal and vertical offsets for spans #1452

rajveermalviya commented Apr 1, 2025

gnprice Apr 22, 2025

gnprice commented Apr 29, 2025

PIG208 left a comment

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

PIG208 May 1, 2025

		_logError('KaTeX: Unsupported CSS property: $property of '
		'type ${expression.runtimeType}');

KaTeX (2/n): Support horizontal and vertical offsets for spans #1452

Are you sure you want to change the base?

KaTeX (2/n): Support horizontal and vertical offsets for spans #1452

Conversation

rajveermalviya commented Apr 1, 2025

Choose a reason for hiding this comment

gnprice commented Apr 29, 2025

PIG208 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment